Texture Mapping

In This Topic

A Texture Mapping (NTextureMapping) is an attribute that specifies how a texture is mapped on a 2D shape. When the shape is painted the texture mapping provides a texture transform, taking into account the dimensions of the texture image as well as the bounding box and the transform of the target shape.

Texture mappings are supported by the fill types that are based on raster images – NImageFill, NAdvancedGradientFill and NHatchFill. In order to apply a texture mapping to a fill, you have to create an instance of the desired texture mapping type and assign it to the TextureMapping property of the fill:

Creating a Texture Mapping	Copy Code
NAlignTextureMapping alignTextureMapping = new NAlignTextureMapping(ENHorizontalAlignment.Left, ENVerticalAlignment.Top); NImageFill imageFill = new NImageFill(someImage); imageFill.TextureMapping = alignTextureMapping;

Creating a Texture Mapping

Copy Code

NAlignTextureMapping alignTextureMapping = new NAlignTextureMapping(ENHorizontalAlignment.Left, ENVerticalAlignment.Top);
NImageFill imageFill = new NImageFill(someImage);
imageFill.TextureMapping = alignTextureMapping;

Following is a list of the available texture mapping types:

Align Texture Mapping

NAlignTextureMapping aligns or centers the image inside the target bounding box. The size of the original texture image is preserved.

The following table demonstrates the combinations of the available options for horizontal and vertical alignment:

	Left	Center	Right
Top
Center
Bottom

In the above examples the image is smaller than the target shape, so the shape is not fully covered. For such cases the tiling option can be enabled – the image will be repeated horizontally and vertically until the shape is filled completely. The following example demonstrates this:

Changing the Tile Mode	Copy Code
alignTextureMapping.TileMode = ENTileMode.Tile;

Following is the output for a top-left aligned image with tiling:

Fixed Texture Mapping

The NFixedTextureMapping type derives from NAlignTextureMapping, adding the ability to align the texture with an arbitrary point. The location of the point is specified as an offset from one of the base points of the target bounding rectangle. The base point is specified with the HorizontalAlignment and VerticalAlignment properties (like in the NAlignTextureMapping). The offset is specified through the HorizontalPosition and VerticalPosition properties, either in DIP units or in percent of the target rectangle's width and height. For example the following code configures the alignment point to be offset with 20 DIPs horizontally and vertically from the top left corner:

Createing a Fixed Texture Mapping	Copy Code
NFixedTextureMapping textureMapping = new NFixedTextureMapping(); textureMapping.HorizontalAlignment = ENHorizontalAlignment.Left; textureMapping.HorizontalPosition = new NMultiLength(ENMultiLengthUnit.Dip, 20); textureMapping.VerticalAlignment = ENVerticalAlignment.Top; textureMapping.VerticalPosition = new NMultiLength(ENMultiLengthUnit.Dip, 20);

Createing a Fixed Texture Mapping

Copy Code

NFixedTextureMapping textureMapping = new NFixedTextureMapping();
textureMapping.HorizontalAlignment = ENHorizontalAlignment.Left;
textureMapping.HorizontalPosition = new NMultiLength(ENMultiLengthUnit.Dip, 20);
textureMapping.VerticalAlignment = ENVerticalAlignment.Top;
textureMapping.VerticalPosition = new NMultiLength(ENMultiLengthUnit.Dip, 20);

The image’s top-left corner is aligned with the specified point and its original size is preserved. The resulting image is displayed below:

If you need to specify an offset in percent units you have to use “Percentage” instead of “Dip” in the constructor of the respective NMultiLength object:

Fixed Texture Mapping with Percent Offset	Copy Code
NFixedTextureMapping textureMapping = new NFixedTextureMapping(); textureMapping.HorizontalAlignment = ENHorizontalAlignment.Right; textureMapping.HorizontalPosition = new NMultiLength(ENMultiLengthUnit.Percentage, -10); textureMapping.VerticalAlignment = ENVerticalAlignment.Bottom; textureMapping.VerticalPosition = new NMultiLength(ENMultiLengthUnit.Percentage, -10);

Fixed Texture Mapping with Percent Offset

Copy Code

NFixedTextureMapping textureMapping = new NFixedTextureMapping();
textureMapping.HorizontalAlignment = ENHorizontalAlignment.Right;
textureMapping.HorizontalPosition = new NMultiLength(ENMultiLengthUnit.Percentage, -10);
textureMapping.VerticalAlignment = ENVerticalAlignment.Bottom;
textureMapping.VerticalPosition = new NMultiLength(ENMultiLengthUnit.Percentage, -10);

This code specifies the alignment point relatively to the bottom right corner of the target rectangle. The horizontal offset is equal to 10 percent of the target rectangle’s width. The vertical offset is equal to 10 percent of the target rectangle’s height. The image’s bottom-right corner is aligned with the thus specified point:

Similarly to the Align Texture Mapping, the Fixed Texture Mapping supports tiling - the image can be repeated to cover the shape’s area completely.

Fit-and-Align Texture Mapping

NFitAndAlignTextureMapping scales the image to fit within the target bounding box, keeping the image’s original aspect ratio. If the aspect ratios of the image and the target bounding box are different, the shape won’t be fully covered in one of the dimensions.

For example if you use an image with size 200 x 100 pixels to fill a square, only half of the square will be covered:

As can be seen, there is some free space in the Y dimension, so the texture mapping allows for the image to be either top aligned, bottom aligned or centered vertically.

The following table demonstrates the available alignment modes and how their combinations affect two images with different aspect ratios:

Horizontal Alignment	Vertical Alignment	Image 1	Image 2
Center	Center
Left	Center
Right	Center
Center	Top
Left	Top
Right	Top
Center	Bottom
Left	Bottom
Right	Bottom

Similarly to the Align Texture Mapping, the Fit and Align Texture Mapping supports tiling - the image can be repeated to cover the shape’s area completely.

Stretch Texture Mapping

NStretchTextureMapping stretches or shrinks the image as much as necessary to fill the target bounding box. The scale factors for the X and Y dimensions may be different, so the original aspect ratio of the image is not preserved.

Stretch X - Align Y Texture Mapping

NStretchXAlignYTextureMapping scales only the X size of the image to cover the width of the target bounding rectangle. Preserves the image’s original Y size.

The table below lists the available options for vertical alignment:

Vertical Alignment
Top
Center
Bottom

This texture mapping type supports tiling - the image can be repeated to cover the shape’s area completely.

Stretch Y - Align X Texture Mapping

NStretchYAlignXTextureMapping scales only the Y size of the image to cover the height of the target bounding rectangle. Preserves the image’s original X size.

The table below lists the available options for horizontal alignment:

Horizontal Alignment
Center
Left
Right

This texture mapping type supports tiling - the image can be repeated to cover the shape’s area completely.

Tile Texture Mapping

NTileTextureMapping tiles the image to cover the target shape. The size of the original texture image is preserved. It is possible to specify that the image is flipped for alternate tiles along the X and the Y dimensions. For example if the FlipX property is set to true every second tile in X will be flipped horizontally. The following table shows the results for the possible combinations of FlipX and FlipY:

	FlipX = false	FlipX = true
FlipY = false
FlipY = true

Custom Texture Mapping

The built-in texture mapping types cover the most common use-cases, but sometimes it is necessary to implement customized texture mapping behavior. In such cases you have to create your own texture mapping type, derived from NCustomTextureMapping and override the following two methods:

GetTileMode must provide the tiling mode to be used by the custom texture mapping.

Calibrate must return a 3x2 matrix that specifies the texture transform.